fill-range

What is fill-range?

The fill-range npm package is used to generate an array of numbers or strings based on a given range with support for steps, negative ranges, and pattern expansion. It is often used for creating lists of numbers, expanding number and letter sequences, and generating arrays based on patterns.

What are fill-range's main functionalities?

Number Range Generation

Generates an array of numbers from 1 to 5.

[...fillRange(1, 5)]

Letter Range Generation

Generates an array of letters from 'a' to 'e'.

[...fillRange('a', 'e')]

Pattern Expansion

Expands a pattern '1..3' and applies a transformation function to each value, resulting in ['item1', 'item2', 'item3'].

[...fillRange('1..3', { transform: (val) => `item${val}` })]

Step Support

Generates an array of numbers from 1 to 10 with a step of 2, resulting in [1, 3, 5, 7, 9].

[...fillRange(1, 10, { step: 2 })]

Negative Range Support

Generates an array of numbers from -3 to 3.

[...fillRange(-3, 3)]

Other packages similar to fill-range

range-generator

This package provides similar functionality to fill-range by generating an array of numbers within a specified range. It allows for custom steps and can handle both ascending and descending ranges. Compared to fill-range, it focuses specifically on number ranges and does not support pattern expansion or letter ranges.

lodash.range

Part of the Lodash utility library, lodash.range generates an array of numbers progressing from start up to, but not including, end. It supports steps and is a lightweight alternative for number range generation. However, it does not offer the pattern expansion or letter range capabilities that fill-range does.

README

fill-range

Fill in a range of numbers or letters, optionally passing an increment or step to use, or create a regex-compatible range with options.toRegex

Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your :heart: and support.

• Install
• Usage
• Examples
• Options
  • options.step
  • options.strictRanges
  • options.stringify
  • options.toRegex
  • options.transform
• About

(TOC generated by verb using markdown-toc)

Install

Install with npm:

$ npm install --save fill-range

Usage

Expands numbers and letters, optionally using a step as the last argument. (Numbers may be defined as JavaScript numbers or strings).

var fill = require('fill-range');
fill(from, to[, step, options]);

// examples
console.log(fill('1', '10'));                  //=> '[ '1', '2', '3', '4', '5', '6', '7', '8', '9', '10' ]'
console.log(fill('1', '10', {toRegex: true})); //=> [1-9]|10

Params

• from: {String|Number} the number or letter to start with
• to: {String|Number} the number or letter to end with
• step: {String|Number|Object|Function} Optionally pass a step to use.
• options: {Object|Function}: See all available options

Examples

By default, an array of values is returned.

Alphabetical ranges

console.log(fill('a', 'e')); //=> ['a', 'b', 'c', 'd', 'e']
console.log(fill('A', 'E')); //=> [ 'A', 'B', 'C', 'D', 'E' ]

Numerical ranges

Numbers can be defined as actual numbers or strings.

console.log(fill(1, 5));     //=> [ 1, 2, 3, 4, 5 ]
console.log(fill('1', '5')); //=> [ 1, 2, 3, 4, 5 ]

Negative ranges

Numbers can be defined as actual numbers or strings.

console.log(fill('-5', '-1')); //=> [ '-5', '-4', '-3', '-2', '-1' ]
console.log(fill('-5', '5')); //=> [ '-5', '-4', '-3', '-2', '-1', '0', '1', '2', '3', '4', '5' ]

Steps (increments)

// numerical ranges with increments
console.log(fill('0', '25', 4)); //=> [ '0', '4', '8', '12', '16', '20', '24' ]
console.log(fill('0', '25', 5)); //=> [ '0', '5', '10', '15', '20', '25' ]
console.log(fill('0', '25', 6)); //=> [ '0', '6', '12', '18', '24' ]

// alphabetical ranges with increments
console.log(fill('a', 'z', 4)); //=> [ 'a', 'e', 'i', 'm', 'q', 'u', 'y' ]
console.log(fill('a', 'z', 5)); //=> [ 'a', 'f', 'k', 'p', 'u', 'z' ]
console.log(fill('a', 'z', 6)); //=> [ 'a', 'g', 'm', 's', 'y' ]

Options

options.step

Type: number (formatted as a string or number)

Default: undefined

Description: The increment to use for the range. Can be used with letters or numbers.

Example(s)

// numbers
console.log(fill('1', '10', 2)); //=> [ '1', '3', '5', '7', '9' ]
console.log(fill('1', '10', 3)); //=> [ '1', '4', '7', '10' ]
console.log(fill('1', '10', 4)); //=> [ '1', '5', '9' ]

// letters
console.log(fill('a', 'z', 5)); //=> [ 'a', 'f', 'k', 'p', 'u', 'z' ]
console.log(fill('a', 'z', 7)); //=> [ 'a', 'h', 'o', 'v' ]
console.log(fill('a', 'z', 9)); //=> [ 'a', 'j', 's' ]

options.strictRanges

Type: boolean

Default: false

Description: By default, null is returned when an invalid range is passed. Enable this option to throw a RangeError on invalid ranges.

Example(s)

The following are all invalid:

fill('1.1', '2');   // decimals not supported in ranges
fill('a', '2');     // incompatible range values
fill(1, 10, 'foo'); // invalid "step" argument

options.stringify

Type: boolean

Default: undefined

Description: Cast all returned values to strings. By default, integers are returned as numbers.

Example(s)

console.log(fill(1, 5));                    //=> [ 1, 2, 3, 4, 5 ]
console.log(fill(1, 5, {stringify: true})); //=> [ '1', '2', '3', '4', '5' ]

options.toRegex

Type: boolean

Default: undefined

Description: Create a regex-compatible source string, instead of expanding values to an array.

Example(s)

// alphabetical range
console.log(fill('a', 'e', {toRegex: true})); //=> '[a-e]'
// alphabetical with step
console.log(fill('a', 'z', 3, {toRegex: true})); //=> 'a|d|g|j|m|p|s|v|y'
// numerical range
console.log(fill('1', '100', {toRegex: true})); //=> '[1-9]|[1-9][0-9]|100'
// numerical range with zero padding
console.log(fill('000001', '100000', {toRegex: true}));
//=> '0{5}[1-9]|0{4}[1-9][0-9]|0{3}[1-9][0-9]{2}|0{2}[1-9][0-9]{3}|0[1-9][0-9]{4}|100000'

options.transform

Type: function

Default: undefined

Description: Customize each value in the returned array (or string). (you can also pass this function as the last argument to fill()).

Example(s)

// increase padding by two
var arr = fill('01', '05', function(val, a, b, step, idx, arr, options) {
  return repeat('0', (options.maxLength + 2) - val.length) + val;
});

console.log(arr);
//=> ['0001', '0002', '0003', '0004', '0005']

About

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Running Tests

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

$ npm install && npm test

Building docs

(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)

To generate the readme, run the following command:

$ npm install -g verbose/verb#dev verb-generate-readme && verb

Related projects

You might also be interested in these projects:

• braces: Bash-like brace expansion, implemented in JavaScript. Safer than other brace expansion libs, with complete support… more | homepage
• expand-range: Fast, bash-like range expansion. Expand a range of numbers or letters, uppercase or lowercase. Used… more | homepage
• micromatch: Glob matching for javascript/node.js. A drop-in replacement and faster alternative to minimatch and multimatch. | homepage
• to-regex-range: Pass two numbers, get a regex-compatible source string for matching ranges. Validated against more than… more | homepage

Contributors

Commits	Contributor
111	jonschlinkert
2	paulmillr
2	realityking
2	bluelovers
1	edorivai
1	wtgtybhertgeghgtwtg

Author

Jon Schlinkert

• LinkedIn Profile
• GitHub Profile
• Twitter Profile

License

Copyright © 2018, Jon Schlinkert. Released under the MIT License.

---

This file was generated by verb-generate-readme, v0.6.0, on July 05, 2018.